i18n-embed
This library contains traits and macros to conveniently embed the output of cargo-i18n into your application binary in order to localize it at runtime.
Currently this library depends on rust-embed to perform the actual embedding of the language files. This may change in the future to make the library more convenient to use.
Optional Features
The i18n-embed
crate has the following optional Cargo features:
fluent-system
- Enable support for the fluent localization system via the
FluentLanguageLoader
.
- Enable support for the fluent localization system via the
gettext-system
- Enable support for the gettext localization system using the tr macro and the gettext crate via the
GettextLanguageLoader
.
- Enable support for the gettext localization system using the tr macro and the gettext crate via the
desktop-requester
- Enables a convenience implementation of
LanguageRequester
trait calledDesktopLanguageRequester
for the desktop platform (windows, mac, linux),which makes use of the locale_config crate for resolving the current system locale.
- Enables a convenience implementation of
web-sys-requester
- Enables a convenience implementation of
LanguageRequester
trait calledWebLanguageRequester
which makes use of the web-sys crate for resolving the language being requested by the user's web browser in a WASM context.
- Enables a convenience implementation of
Example
The following is a minimal example for how localize your binary using this library using the fluent localization system.
First you need to compile i18n-embed
in your Cargo.toml
with the fluent-system
and desktop-requester
features enabled:
[]
= { = "0.10", = ["fluent-system", "desktop-requester"]}
= "5"
= "0.9"
Set up a minimal i18n.toml
in your crate root to use with cargo-i18n
(see cargo i18n for more information on the configuration file format):
# (Required) The language identifier of the language used in the
# source code for gettext system, and the primary fallback language
# (for which all strings must be present) when using the fluent
# system.
= "en-GB"
# Use the fluent localization system.
[]
# (Required) The path to the assets directory.
# The paths inside the assets directory should be structured like so:
# `assets_dir/{language}/{domain}.ftl`
= "i18n"
Next, you want to create your localization resources, per language fluent files. language
needs to conform to the Unicode Language Identifier standard, and will be parsed via the unic_langid crate.
The directory structure should look like so:
my_crate/
Cargo.toml
i18n.toml
src/
i18n/
{language}/
{domain}.ftl
Then you can instantiate your language loader and language requester:
use ;
use RustEmbed;
// path to the compiled localization resources
;
To access localizations, you can use FluentLanguageLoader
's methods directly, or, for added compile-time checks/safety, you can use the fl!() macro. Having an i18n.toml
configuration file enables you to do the following:
- Use the cargo i18n tool to perform validity checks (not yet implemented).
- Integrate with a code-base using the
gettext
localization system. - Use the
fluent::fluent_language_loader!()
macro to pull the configuration in at compile time to create thefluent::FluentLanguageLoader
. - Use the fl!() macro to have added compile-time safety when accessing messages.
For more examples, see the documentation for i18n-embed.